home *** CD-ROM | disk | FTP | other *** search
Text File | 1998-03-19 | 39.7 KB | 1,569 lines | [TEXT/MPS ] |
- (*
- File: Ivy Task Library for Virtual User 2.1 version 1.2b3
-
- Contains: The Ivy 1.2 Virtual User tool declaration.
-
- Written by: Rich Millet
-
- Copyright: © 1994-1997 by Apple Computer, Inc., all rights reserved.
-
- *)
-
- #
- # Change history (most recent first):
- # Version Date Who Comments
- # ======= ======== === =============
- # 1.4.0 02/03/97 JAS Added 'vers' resources to library.
- # These should always match tool version when tool is revved.
- #
- #
-
- Libraries "Ivy Tool Declaration.vulib";
-
- #--------------------------------------------------------------------------------------------------
-
- #
- # find Δ/•#∂tIV≈∂)∞/
- # find /IV[a-z_0-9]+/
- # mark -y § "`catenate "{Target}".§`"
- # find Δ§
- #
-
- # INITIALIZATION TASKS
-
- # IVInit( theLocation, theBoolean := false )
- #
- # Purpose:
- # To open and initialize the Ivy application.
- #
- # Inputs:
- # theLocation - a Boolean value indicating whether you want Ivy opened on the
- # target or host machine. Passing a true value opens Ivy on the
- # target. Passing a false value opens Ivy on the host.
- #
- # theBoolean _ Ignore this parameter, unless you are using scripts written for the Ivy 1.0 task library.
- # It is a Boolean value indicating whether or not to support the Ivy 1.0
- # style of returning task results. A true value will ensure compatibility with
- # scripts written using the Ivy 1.0 task library.
- #
- # Outputs:
- # result - a Boolean value indicating success or failure; true = success, false = failure.
- #
- # Notes:
- # Your script must call this task before using any other Ivy tasks!
- #
- # This task initializes the image information globals(constants). Use these globals to index
- # the list of values returned by the 'IVGetImageFileInfo' task. It also initializes font
- # style constants that you should use when writing scripts with the IVLocateString() task.
- #
- # Example:
- #
- # result := IVInit( false );
- # if ( result <> true )
- # begin
- # # Handle error here.
- # end;
- #
- Task IVInit( theLocation, theBoolean := false )
- begin
- global kIVLibraryVersion := 120;
- global kIVLibraryVersionString := '1.2';
-
- global kImageFrame := 1;
- global kIvyVersion := 2;
- global kImageSize := 3;
- global kImageBitMapChecksum := 4;
- global kImageRGBChecksum := 5;
- global kImagePixelCount := 6;
- global kImageBitDepth := 7;
- global kImageDateStamp := 8;
- global kImageTimeStamp := 9;
-
- global kNormal := 0;
- global kBold := 1;
- global kItalic := 2;
- global kUnderline := 4;
- global kOutline := 8;
- global kShadow := 16;
- global kCondense := 32;
- global kExtend := 64;
- # if true, the Ivy 1.1 tasks return the entire external tool result list.
- global gIVResultList := theBoolean; # Set to true for backward compatibility with scripts written for the
- # Ivy 1.0 task library.
-
- resultList := Ivy( "INITIALIZE", theLocation ); # true launches on the target, false on the host.
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- return false;
-
- resultList := Ivy( "IVInit" ); # prepares Ivy's core routines.
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- return false;
-
- toolVersionString := IVGetToolVersion();
-
- if ( toolVersionString[1] < kIVLibraryVersion )
- begin
- println "IVInit - The Ivy external tool is out of date relative to Ivy's task library.";
- println "IVInit - The Ivy external tool version is : ", toolVersionString[3];
- println "IVInit - Upgrade the Ivy external tool to a version greater than or equal to ", kIVLibraryVersionString;
- return false;
- end;
-
- IVSetExceptionHandler(); # set up default exception handling;
- IVStopWaitForImage(); # clear any pending ‘wait for image’ tasks.
-
- return true;
- end;
-
-
- # IVError()
- #
- # Purpose:
- # To return the result list of the last Ivy task called.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - a list of three values: { errorCode, taskValue, error message }
- # taskValue - differs for each task.
- #
- # Notes:
- # None.
- #
- # See also:
- # IVSetExceptionHandler()
- #
- # Example:
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # …
- # end;
- #
- Task IVError()
- begin
- return global gIVError;
- end;
-
-
- # IVSetExceptionHandler( theHandler := Task IVDefaultHandler )
- #
- # Purpose:
- # To install an exception handling task for all Ivy task calls.
- #
- # Inputs:
- # theHandler - a task reference. Ivy will call ‘theHandler’ whenever one of its tasks
- # encounters an error.
- #
- # Outputs:
- # None. Does not affect the results of IVError().
- #
- # Notes:
- # Does not affect the results of IVError().
- #
- # See also:
- # IVDefaultHandler()
- # IVError();
- #
- # Example:
- #
- # IVSetExceptionHandler( Task YourTaskName );
- #
- Task IVSetExceptionHandler( theHandler := Task IVDefaultHandler )
- begin
- global gIVExceptionHandler := theHandler;
- end;
-
-
- # IVGetExceptionHandler()
- #
- # Purpose:
- # To get a task reference to the current Ivy exception handler.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - a task reference to Ivy’s current exception handler.
- #
- # Notes:
- # Does not affect the results of IVError();
- #
- # See also:
- # IVSetExceptionHandler()
- # IVDefaultHandler()
- #
- # Example:
- #
- # exceptionHandler := IVGetExceptionHandler();
- #
- Task IVGetExceptionHandler()
- begin
- global gIVExceptionHandler;
-
- if ( isUndefined( gIVExceptionHandler ) = false )
- return gIVExceptionHandler;
- else
- begin
- println;
- println "### Error - Ivy has not been initialized. See description of IVInit() task.";
- println;
- exit;
- end;
- end;
-
-
- # IVDefaultHandler( theResultList )
- #
- # Purpose:
- # To be the default Ivy task exception handler. This handler prints out the error message
- # and returns the task return value.
- #
- # Inputs:
- # theResultList - a list of three values: { errorCode, taskValue, error message }
- #
- # Outputs:
- # taskValue - the ‘taskValue’ of ‘theResultList’.
- #
- # Notes:
- # Applicable notes.
- #
- # See also:
- # IVSetExceptionHandler()
- # IVGetExceptionHandler()
- # IVError();
- #
- Task IVDefaultHandler( theResultList )
- begin
- println theResultList;
-
- return theResultList[2];
- end;
-
-
- # IVGetToolVersion( )
- #
- # Purpose:
- # To find out the version of the external tool.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - a string containing Ivy's external tool version.
- #
- # Notes:
- # Applicable notes.
- #
- # Example:
- #
- # versionString := IVGetToolVersion();
- #
- Task IVGetToolVersion( )
- begin
- resultList := Ivy( "GETTOOLVERSION" );
- global gIVError := resultList;
-
- versionNumber := Ivy( "IVGETTOOLVERSION" )[2];
-
- return { versionNumber } + resultList[2];
- end;
-
-
- # IVQuit( )
- #
- # Purpose:
- # To close (or quit) Ivy.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - undefined.
- #
- # Notes:
- # Applicable notes.
- #
- # Example:
- #
- # IVQuit();
- #
- Task IVQuit( )
- begin
- resultList := Ivy( "QUIT" );
- global gIVError := resultList;
-
- return resultList[2];
- end;
-
-
- Task HandleResultList( theResultList, theTaskName )
- begin
- if ( isUndefined( theResultList ) or ( card theResultList < 2 ) )
- begin
- newResultList := { -1, Undefined, "### Error - An unknown error in Ivy occurred." };
- end;
- else
- begin
- if ( theResultList[1] <> 0 )
- begin
- if ( isUndefined( theResultList[3] ) )
- newResultList := { theResultList[1], theResultList[2], theTaskName + " - No description for this error is available." };
- else
- newResultList := replace( theTaskName + " - " + theResultList[3], 3, theResultList );
- end;
- else
- begin
- newResultList := theResultList;
- end;
- end;
-
- return newResultList;
- end;
-
-
- #--------------------------------------------------------------------------------------------------
-
- # TASKS TO SEND COMMANDS TO TOOLS LIKE MACSTIME
-
- # IVSetToolCmd( theToolID, theCommand, theContext, theParam1, theParam2, theParam3, theParam4 )
- #
- # Purpose:
- # To have Ivy send a command to a tool when Ivy starts looking for or when it detects the
- # appearance of an image. In this version of Ivy, Ivy can send only ONE command; that is, Ivy
- # can NOT send two commands when it starts looking for or detects the appearance of an image.
- #
- # Inputs:
- # theToolID - a four character string identifying the tool to receive
- # the command ‘Command’. The string should be the four character Gestalt
- # selector that the tool registered with the Gestalt Manager.
- #
- # theContext - a boolean flag.
- #
- # false - Ivy will send the command when it starts looking for the image.
- # true - Ivy will send the command when it detects the appearance of the image.
- #
- # theCommand - an integer identifying which of the tool's commands to execute.
- #
- # theParam1 through theParam4 - the parameters for the ‘theCommand’ request that Ivy
- # sends to the tool.
- #
- # Outputs:
- # result - None
- #
- # Notes:
- # None
- #
- # See also:
- # IVStartWaitForImage()
- # IVStopWaitForImage()
- # IVWaitForImage()
- # IVUnsetToolCmd()
- #
- # Example:
- #
- # theResult := IVSetToolCmd( 'maxt', 4, true, 0, 0, 0, 0 );
- #
- # This example, sets up Ivy to send MacsTime (maxt) a 'StopNow' command when it detects the
- # appearance of an image.
- #
- Task IVSetToolCmd( theToolID, theCommand, theContext := true, theParam1 := 0, theParam2 := 0, theParam3 := 0, theParam4 := 0 )
- begin
- resultList := Ivy( "IVSETTOOLCMD", theToolID, theCommand, theContext, theParam1, theParam2, theParam3, theParam4 );
-
- resultList := HandleResultList( resultList, "IVSetToolCmd" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- return Call( IVGetExceptionHandler(), resultList );
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVUnsetToolCmd( theToolID )
- #
- # Purpose:
- # To unset all tool commands set by the task IVSetToolCmd(). In this version of Ivy, Ivy can
- # send only one command; that is, Ivy can not send two tools commands when it starts looking for or
- # detects the appearance of an image.
- #
- # Inputs:
- # theToolID - a four character string identifying the tool to receive
- # the command ‘Command’. The string should be the four character Gestalt
- # selector that the tool registered with the Gestalt Manager.
- #
- # Outputs:
- # None.
- #
- # Notes:
- # None.
- #
- # See also:
- # IVSetToolCmd()
- #
- # Example:
- #
- # IVUnsetToolCmd( 'maxt' );
- #
- Task IVUnsetToolCmd( theToolID )
- begin
- resultList := Ivy( "IVUNSETTOOLCMD", theToolID );
-
- resultList := HandleResultList( resultList, "IVUnsetToolCmd" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVSendToolCmd( theToolID, theCommand, theParam1, theParam2, theParam3, theParam4 )
- #
- # Purpose:
- # To get a task reference to the current Ivy exception handler.
- #
- # Inputs:
- # theToolID - a four character string identifying the tool to receive
- # the command ‘Command’. The string should be the four character Gestalt
- # selector that the tool registered with the Gestalt Manager.
- #
- # theCommand - an integer identifying which of the tool's commands to execute.
- #
- # theParam1 through theParam4 - the parameters for the ‘theCommand’ request that Ivy
- # sends to the tool.
- #
- # Outputs:
- # result - the result of the command 'theCommand'.
- #
- # Notes:
- # None.
- #
- # See also:
- # IVSetStopImageCmd()
- # IVClearStopImageCmd()
- #
- # Example:
- #
- # theResult := IVSendToolCmd( 'maxt', 4, 0, 0, 0, 0 );
- #
- # This example sends the MacsTime tool (maxt) a 'StopNow' command.
- #
- Task IVSendToolCmd( theToolID, theCommand, theParam1 := 0, theParam2 := 0, theParam3 := 0, theParam4 := 0 )
- begin
- resultList := Ivy( "IVSENDTOOLCMD", theToolID, theCommand, theParam1, theParam2, theParam3, theParam4 );
-
- resultList := HandleResultList( resultList, "IVSendToolCmd" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- #--------------------------------------------------------------------------------------------------
-
- # TASKS TO SET THE CURRENT DIRECTORY AND DELETE FILES
-
- # IVSetDirectory( thePathName )
- #
- # Purpose:
- # To sets Ivy’s default file directory.
- #
- # Inputs:
- # thePathName - a string describing a full or partial path name.
- #
- # Outputs:
- # result - a string describing the new full path name.
- #
- # Notes:
- # If you never call this task, Ivy's default directory will be the directory in
- # which the Ivy application file resides.
- #
- # See also:
- # IVSetDirectory();
- #
- # Example:
- #
- # result := IVSetDirectory( "HD 80SC:Jane’s Folder:Images:" );
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not set the directory - ", errorList;
- # end;
- #
- Task IVSetDirectory( thePathname )
- begin
- resultList := Ivy( "IVSETDIRECTORY", thePathname );
-
- resultList := HandleResultList( resultList, "IVSetDirectory" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVGetDirectory()
- #
- # Purpose:
- # To get Ivy’s default directory.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - a string describing Ivy’s default directory.
- #
- # Notes:
- # With this task, your script can determine where Ivy is creating and looking for
- # image files.
- #
- # See also:
- # IVSetDirectory();
- #
- # Example:
- #
- # tPathName := IVGetDirectory();
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not get the directory pathname- ", errorList;
- # end;
- #
- Task IVGetDirectory()
- begin
- resultList := Ivy( "IVGETDIRECTORY" );
-
- resultList := HandleResultList( resultList, "IVGetDirectory" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVDeleteImageFile( theFileName )
- #
- # Purpose:
- # To delete an image file.
- #
- # Inputs:
- # theFileName - a string containing the name of the file to delete.
- #
- # Outputs:
- # result - a Boolean value indicating success or failure; 1 is success and 0 is failure.
- #
- # See also:
- # IVCreateImageFile()
- #
- # Example:
- #
- # result := IVDeleteImageFile( "Pam’s Image File" );
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not delete the image file - ", errorList;
- # end;
- #
- Task IVDeleteImageFile( theFileName )
- begin
- kFileNotFound := -43;
-
- resultList := Ivy( "IVDELETEIMAGE", theFileName );
-
- resultList := HandleResultList( resultList, "IVDeleteImageFile" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 and resultList[1] <> kFileNotFound )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- #--------------------------------------------------------------------------------------------------
-
-
- # TASKS TO CAPTURE AND COMPARE 'PICT' SCREEN IMAGE FILES
-
-
- Task IVRectangleDefined( theRectangle )
- begin
- if ( isUndefined( theRectangle ) = true )
- return false;
-
- if ( isUndefined( theRectangle[1] ) or isUndefined( theRectangle[2] ) or
- isUndefined( theRectangle[3] ) or isUndefined( theRectangle[4] ) )
- return false;
-
- return true;
- end;
-
-
- # IVCreateImageFile( theFileName, theImageRectangle, theIgnoreRectangles := { } )
- #
- # Purpose:
- # To create a file which contains a PICT resource containing a screen image.
- #
- # Inputs:
- # theFileName - a string containing the name of the file to create.
- #
- # theImageRectangle - the rectangle enclosing the screen image to capture; { left, top,
- # right, bottom }.
- #
- # theIgnoreRectangles - a list of rectangles inside 'theImageRectangle' which Ivy will erase
- # before creating the 'PICT' resource.
- #
- # Outputs:
- # result - a 32 bit integer representing the checksum value of the image.
- #
- # See also:
- # IVError()
- # IVDeleteImageFile()
- #
- # Notes:
- # WARNING: This task will delete any existing file named 'theFileName' before creating the
- # new file.
- #
- # Example:
- #
- # result := IVCreateImageFile( "Pam’s Image File", { 0, 0, 100, 100 } );
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not create the image file - ", errorList;
- # end;
- #
- Task IVCreateImageFile( theFileName, theImageRectangle, theIgnoreRectangles := { } ) # return boolean
- begin
-
- # if ( IVRectangleDefined( theImageRectangle ) = false )
- # begin
- # resultList := { 0, 0, "The rectangle passed to IVCreateImageFile was either undefined or contained an undefined element." };
- # return Call( IVGetExceptionHandler(), resultList );
- # end;
-
- kDupFNErr := -48;
- resultList := { kDupFNErr };
-
- while ( resultList[1] = kDupFNErr )
- begin
- Ivy( "IVDELETEIMAGE", theFileName );
- resultList := Ivy( "IVCREATEIMAGE", theFileName, theImageRectangle, theIgnoreRectangles );
- end;
-
- resultList := HandleResultList( resultList, "IVCreateImageFile" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVCompareImageFiles( theFirstFileName, theSecondFileName, theResultFileName, theIgnoreRectangles := { } )
- #
- # Purpose:
- # To compare two image files. If the two images differ, the task will create a new image
- # containing the differences.
- #
- # Inputs:
- # theFirstFileName - a string containing the first image’s file name.
- #
- # theSecondFileName - a string containing the second image’s file name.
- #
- # theResultFileName - if the two images do not match, this file name will be used to
- # create a new image file showing where the first two images differ.
- # If your script passes an empty string ("" or ''), Ivy will not
- # create a difference image.
- #
- # theIgnoreRectangles - a list of rectangular areas to ignore when performing the compar-
- # ison. Each rectangle (which are lists themselves, of the form
- # { left, top, right, bottom }) should be expressed in local co-
- # ordinates relative to the first image; that is, assume the top-left
- # corner of the first image is (0, 0).
- #
- # Outputs:
- # result - a Boolean value: '1' means the images matched, '0' means the images
- # did not match.
- #
- # See also:
- # IVCreateImageFile()
- #
- # Example:
- #
- # result := IVCompareImageFiles( "Yin", "Yang", "Yin&Yang", { { 0, 0, 5, 5 }, { 5, 0, 10, 5 } } );
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not compare the image files - ", errorList;
- # end;
- #
- Task IVCompareImageFiles( theFirstFileName, theSecondFileName, theResultFileName, theIgnoreRectangles := { } ) # return boolean
- begin
- Ivy( "IVDELETEIMAGE", theResultFileName );
-
- resultList := Ivy( "IVCOMPAREIMAGES", theFirstFileName,
- theSecondFileName,
- theResultFileName,
- theIgnoreRectangles );
-
- resultList := HandleResultList( resultList, "IVCompareImageFiles" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVGetImageFileInfo( theFileName )
- #
- # Purpose:
- # To obtain information about an image that Ivy created.
- #
- # Inputs:
- # theFileName - a string containing the file name of an image.
- #
- # Outputs:
- # result - a list of the following values: an enclosing rectangle, the bit depth of the
- # image, the size of the image in bytes, the unsigned 32 bit checksum of the
- # image, and the time and date the image was created. See the notes below.
- #
- # Notes:
- # To ensure future compatibility with Ivy, use the following globals when accessing elements of the list
- # returned by IVGetImageFileInfo.
- #
- # global kImageFrame;
- # global kIvyVersion;
- # global kImageSize;
- # global kImageBitMapChecksum;
- # global kImagePixelCount;
- # global kImageBitDepth;
- # global kImageTimeStamp;
- # global kImageDateStamp;
- #
- # See also:
- # IVCreateImageFile()
- #
- # Example:
- #
- # infoList := IVGetImageInfo( "Dialog Image" );
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not set the directory - ", errorList;
- # end
- # else
- # println "The image was created on ", infoList[ global kImageDateStamp ];
- #
- Task IVGetImageFileInfo( theFileName, theImageName := "" )
- begin
- resultList := Ivy( "IVGETIMAGEINFO", theFileName );
-
- resultList := HandleResultList( resultList, "IVGetImageFileInfo" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- #--------------------------------------------------------------------------------------------------
-
-
- # TASKS TO CALCULATE SCREEN IMAGE CHECKSUMS
-
-
- # IVChecksumRectangle( theScreenRectangle )
- #
- # Purpose:
- # To calculate a simple check sum of the screen image enclosed in the 'theScreenRectangle.'
- #
- # Inputs:
- # theScreenRectangle - a list of four values describing a rectangle; e.g. { left, top,
- # right, bottom }.
- #
- # Outputs:
- # result - an unsigned 32 bit checksum.
- #
- # Notes:
- # This task creates a check sum of screen memory. If screen is running in 2, 4, or 8 bit color mode, the check
- # sum value will be dependent upon the screen’s current color lookup table.
- #
- # See also:
- # IVCreateChecksumFile()
- #
- # Example:
- #
- # result := IVChecksumRectangle( { 0, 0, 20, 30 } );
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not checksum the rectangle - ", errorList;
- # end;
- #
- Task IVChecksumRectangle( theScreenRectangle ) # return a string representing a 32 bit unsigned integer
- begin
- resultList := Ivy( "IVCHECKSUMIMAGE", "", theScreenRectangle, false );
-
- resultList := HandleResultList( resultList, "IVChecksumRectangle" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVCreateChecksumFile( theFileName, theScreenRectangle )
- #
- # Purpose:
- # To create a file which contains the check sum of a screen image.
- #
- # Inputs:
- # theFileName - a string containing the name of the new file.
- #
- # theScreenRectangle - a list of four values describing a rectangle; e.g. { left, top,
- # right, bottom }.
- #
- # Outputs:
- # result - a Boolean value indicating success or failure; 1 is success and
- # 0 is failure.
- #
- # Notes:
- #
- # This task creates a new file named imageName and stores the 32 bit checksum value in the
- # resource fork of the file; in a type 'IVYC' resource.
- #
- # See also:
- # IVChecksumRectangle()
- # IVGetImageFileInfo()
- #
- # Example:
- #
- # result := IVCreateChecksumFile( "Alice’s Checksum", { 15, 20, 45, 30 } );
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not create the checksum file - ", errorList;
- # end;
- #
- Task IVCreateChecksumFile( theFileName, theImageRectangle )
- begin
- if ( IVRectangleDefined( theImageRectangle ) = false )
- begin
- resultList := { 0, 0, "The rectangle passed to IVCreateChecksumFile was either undefined or contained an undefined element." };
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- kDupFNErr := -48;
- resultList := { kDupFNErr };
-
- while ( resultList[1] = kDupFNErr )
- begin
- Ivy( "IVDELETEIMAGE", theFileName );
- resultList := Ivy( "IVCHECKSUMIMAGE", theFileName, theImageRectangle, true );
- end;
-
- resultList := HandleResultList( resultList, "IVCreateChecksumFile" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- #--------------------------------------------------------------------------------------------------
-
-
- # PERFORMANCE TASKS
-
- # IVCallOverhead()
- #
- # Purpose:
- # To calculate the round trip overhead time involved in making a call to Ivy. When using
- # Ivy to time an operation, subtract the result of this call from the difference of your
- # start and stop times; for example:
- #
- # finalTime := stopTime - startTime - IVCallOverhead();
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # taskValue - a string representing a 32 bit unsigned integer. The number represents the
- # time (in milliseconds) it took to make a call to, and return from, Ivy.
- #
- # Notes:
- # Applicable notes.
- #
- # See also:
- # Task()
- #
- # Example:
- #
- # overheadTime := IVCallOverhead();
- #
- # errorList := IVError();
- # if ( errorList[1] <> 0 )
- # begin
- # println "Could not get the overhead time - ", errorList;
- # end;
- #
- task IVCallOverhead()
- begin
- kTrips := 3;
-
- total := 0;
- for i := 1 to kTrips
- begin
- startTime := IVGetCurrentTime();
- stopTime := IVGetCurrentTime();
-
- delta := IVSubtractTimes( stopTime, startTime );
-
- if ( typeOf( delta ) = 'String' )
- delta := StrToNum( delta );
-
- total := total + delta;
- end;
-
- return NumToStr( total / kTrips );
- end;
-
-
- # IVPoll( theJobID )
- #
- # Purpose:
- # To poll for the results of an asynchronous task call; in this version of Ivy, you can call
- # only IVWaitForImage asynchronously.
- #
- # Inputs:
- # theJobID - the asynchronous job ID.
- #
- # Outputs:
- # result - until the asynchronous task completes, ‘result’ will contain a list of
- # two values: { 1, theJobID }. Once the asynchronous task completes, ‘result’
- # will contain the result corresponding the asynchronous task.
- #
- # Notes:
- # See the section titled “Calling External Tools Asynchronously” in the “Using External Tools” chapter of the
- # “Virtual User Language Reference.”
- #
- # See also:
- # IVWaitForImage()
- #
- # Example:
- #
- # resultList := IVWaitForImage( "Cindy’s slipper", { 0, 0, 100, 100 }, 5 ); # Make an asynchronous task call
- # jobID = resultList[2];
- # # Now poll until the asynchronous task call finishes.
- # while ( resultList[1] = 1 and resultList[2] = jobID ) do # Make sure you check for the job ID.
- # if ( resultList[1] <> 0 )
- # begin
- # resultList := IVPoll( jobID );
- # end;
- #
- Task IVPoll( theJobID )
- begin
- resultList := Ivy( "POLL", theJobID );
- global gIVError := resultList;
-
- if ( resultList[1] = 1 and resultList[2] = theJobID )
- begin
- return resultList;
- end;
- else
- begin
- if ( resultList[1] <> 0 )
- begin
- resultList := HandleResultList( resultList, "IVPoll asynchronous job " + theJobID );
- return Call( IVGetExceptionHandler(), resultList );
- end;
- else
- begin
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
- end;
- end;
-
-
- # IVCancel( theJobID )
- #
- # Purpose:
- # To cancel a call to an asynchronous task call; in this version of Ivy, you can call
- # only IVWaitForImage asynchronously.
- #
- # Inputs:
- # theJobID - the asynchronous job ID.
- #
- # Outputs:
- # result - an error code.
- #
- # Notes:
- # See the section titled “Calling External Tools Asynchronously” in the “Using External Tools”
- # chapter of the “Virtual User Language Reference.”
- #
- # See also:
- # IVPoll()
- #
- # Example:
- #
- # resultList := IVWaitForImage( "Cindy’s slipper", { 0, 0, 100, 100 }, 5 ); # Make an asynchronous task call
- # jobID = resultList[2];
- #
- # result := IVCancel( jobID ); # Now cancel the asynchronous task call.
- #
- Task IVCancel( theJobID )
- begin
- resultList := Ivy( "CANCEL", theJobID );
-
- resultList := HandleResultList( resultList, "IVCancel" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- return resultList[1];
- end;
-
-
- # IVWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage := 5 )
- #
- # Purpose:
- # This is an asynchronous task. Before using this task, read and understand the section titled “Calling External
- # Tools Asynchronously” in the “Using External Tools” chapter of the “Virtual User Language Reference.”
- #
- # This task installs an Ivy interrupt routine on the target. The interrupt routine will watch for an image and
- # detect when the image first appears.
- #
- # Inputs:
- # theFileName - a string containing the file name of the image.
- #
- # theWaitRectangle - the EXACT screen location where the image will appear; { left, top,
- # right, bottom }.
- #
- # theCPUPercentage - the percent of CPU time the task should use while looking for an image.
- #
- # Outputs:
- # result - a list of four values: { startTime, timeFound, ivyUsed, frequency }
- #
- # startTime - an 32 bit integer indicating the time (in milliseconds) when Ivy
- # started looking for the image.
- #
- # timeFound - an 32 bit integer indicating the time (in milliseconds) when Ivy
- # first "saw" the image appear on the screen.
- #
- # ivyUsed - an 32 bit integer indicating the time (in milliseconds) used by Ivy
- # while waiting for the image to appear.
- #
- # frequency - an 32 bit integer indicating the time interval (in milliseconds) at
- # which Ivy checked the screen to see if the image appeared.
- #
- # Notes:
- # See the section titled “Calling External Tools Asynchronously” in the “Using External Tools” chapter of the
- # “Virtual User Language Reference.”
- #
- # See also:
- # IVPoll()
- # IVCancel()
- #
- # Example:
- #
- # resultList := IVWaitForImage( "Achille’s Thumb", { 20, 100, 25, 100 }, 5 );
- # jobID := resultList[2];
- #
- # pressMouse; # Start the operation you're timing
- #
- # while ( resultList[1] = 1 and resultList[2] = jobID ) # Poll until Ivy finds the image
- # begin
- # resultList := IVPoll( jobID );
- # end;
- #
- # releaseMouse; # Stop the operation, if necessary
- #
- # waitResultList := resultList; # Get the results of the task call
- #
- # totalTime := IVSubtractTimes( waitResultList[2], waitResultList[1] ); # Subtract the startTime from the timeFound
- #
- # operationTime := IVSubtractTimes( totalTime, waitResultList[3] ); # Subtract off the time Ivy used wait for the image
- #
- Task IVWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage := 5 )
- begin
-
- if ( IVRectangleDefined( theWaitingRectangle ) = false )
- begin
- resultList := { 0, 0, "The rectangle passed to IVWaitForImage was either undefined or contained an undefined element." };
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- resultList := Ivy( "IVWAITFORIMAGE", theFileName, theWaitingRectangle, theCPUPercentage ) async: TRUE;
- global gIVError := resultList;
-
- if ( resultList[1] <> 1 or isUndefined( resultList[2] ) )
- begin
- resultList := HandleResultList( resultList, "IVWaitForImage" );
-
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- return resultList;
- end;
-
-
- # IVStartWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage )
- #
- # Purpose:
- # To install the Ivy interrupt routine on the target that will watch for an image and time
- # when the image appears.
- #
- # Inputs:
- # theFileName - a string containing the file name of the image.
- #
- # theWaitRectangle - the exact screen location where the image will appear; { left, top,
- # right, bottom }.
- #
- # theCPUPercentage - the percent of CPU time the task should use while looking for an image.
- #
- # Outputs:
- # result - a list of two values: { startTime, frequency }
- #
- # startTime - an unsigned 32 bit integer indicating the time (in milliseconds)
- # of the target machine when the task was installed.
- #
- # frequency - an unsigned 32 bit integer indicating the time interval (in mill-
- # iseconds) at which Ivy checked the screen to see if the image appeared.
- #
- # Notes:
- # A millisecond equals 1/1000th of a second.
- #
- # See also:
- # IVGetTimeFound()
- # IVRemoveWaitForImageFile()
- # IVGetCurrentTime()
- # IVSubtractTimes()
- #
- # Example:
- #
- # result := IVStartWaitForImage( "Achille’s Thumb", { 20, 100, 25, 100 }, 5 );
- #
- Task IVStartWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage )
- begin
-
- if ( IVRectangleDefined( theWaitingRectangle ) = false )
- begin
- resultList := { 0, 0, "The rectangle passed to IVStartWaitForImage was either undefined or contained an undefined element." };
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- resultList := Ivy( "IVSTARTWAITFORIMAGE", theFileName, theWaitingRectangle, theCPUPercentage );
-
- resultList := HandleResultList( resultList, "IVStartWaitForImage" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVGetTimeFound()
- #
- # Purpose:
- # To determine when the Ivy interrupt routine first found the image for which it was asked to wait.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - a string containing an unsigned 32 bit integer. The integer is the time (in milli-
- # seconds) of the target machine when Ivy first spotted the image. If the image has
- # not yet appeared, IVGetTimeFound() will return 0.
- #
- # Notes:
- # A millisecond equals 1/1000th of a second.
- #
- # See also:
- # IVStartWaitForImage()
- # IVStopWaitForImage()
- # IVWaitForImage()
- #
- # Example:
- #
- # resultList := IVGetTimeFound();
- #
- Task IVGetTimeFound()
- begin
- resultList := Ivy( "IVGETTIMEFOUND", 0 );
-
- resultList := HandleResultList( resultList, "IVGetTimeFound" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVStopWaitForImage()
- #
- # Purpose:
- # To remove the Ivy “wait for image” interrupt routine and to find out how much time (in milliseconds)
- # the interrupt routine used while waiting for the image to appear.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - a string representing an unsigend 32 bit integer. The integer represents the
- # time (in milliseconds) used by Ivy while waiting for the image to appear.
- #
- # Notes:
- # A millisecond equals 1/1000th of a second.
- #
- # See also:
- # IVStartWaitForImage()
- # IVGetTimeFound()
- #
- # Example:
- #
- # resultList := IVStopWaitForImage();
- #
- Task IVStopWaitForImage()
- begin
- resultList := Ivy( "IVSTOPWAITFORIMAGE", 0 );
-
- resultList := HandleResultList( resultList, "IVStopWaitForImage" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVGetCurrentTime()
- #
- # Purpose:
- # To get the current time (in milliseconds) of the target machine.
- #
- # Inputs:
- # None.
- #
- # Outputs:
- # result - a string represent a 32 bit unsigned integer. The integer represents the time (in milliseconds)
- # of the target machine; the machine upon which Ivy is running.
- #
- # Notes:
- # A millisecond equals 1/1000th of a second.
- #
- # See also:
- # IVSubtractTimes()
- #
- # Example:
- #
- # resultList := IVGetCurrentTime();
- #
- Task IVGetCurrentTime()
- begin
- resultList := Ivy( "IVGETCURRENTTIME" );
-
- resultList := HandleResultList( resultList, "IVGetCurrentTime" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVSubtractTimes( theMinuend, theSubtrahend ))
- #
- # Purpose:
- # To subtract two strings representing unsigned 32 bit integers.
- #
- # Inputs:
- # theMinuend - the number from which the theSubtrahend is subtracted.
- # theSubtrahend - the number subtracted from the minuend; e.g., theMinuend - theSubtrahend = theDifference.
- #
- # Outputs:
- # result - a string representing a 32 bit unsigned integer.
- #
- # Notes:
- # Use the Virtual User’s built-in task StrToNum() to convert the result of IVSubtractTimes() into a
- # V.U. integer. If the string represents a number greater than 32767, StrToNum() will return 'undefined'.
- #
- # See also:
- # IVGetCurrentTime()
- # IVGetTimeFound()
- #
- # Example:
- #
- # result := IVSubtractTimes( "45900", "45800" );
- #
- # theDifference := StrToNum( resultList[2] );
- #
- Task IVSubtractTimes( theMinuend, theSubtrahend )
- begin
- resultList := Ivy( "IVSUBTRACTTIMES", theMinuend, theSubtrahend );
-
- resultList := HandleResultList( resultList, "IVSubtractTimes" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- #--------------------------------------------------------------------------------------------------
-
-
- # ÏÏÏ SEARCH TASKS
-
-
- # IVLocateImageFile( theFileName, theSearchRectangle, theLastLocation := { -32767, -32767 } )
- #
- # Purpose:
- # To find the location of a screen image.
- #
- # Inputs:
- # theFileName - a string containing the file name of the image.
- #
- # theLocation - the screen rectangle in which to search; { left, top, right, bottom }.
- #
- # theLastLocation - the rectangle (or just its left and top points) where Ivy last found the image. Use
- # this parameter to find the next occurance of an image inside a given search rectangle.
- #
- # Outputs:
- # result - a rectangle describing the location of the image; { left, top, right, bottom }.
- #
- # Notes:
- # If the task does not find the image, it returns the following rectangle { 0, 0, 0, 0 }.
- #
- # See also:
- # IVLocateString()
- #
- # Example:
- #
- # resultList := IVLocateImageFile( "The lost image", { 0, 0, 640, 480 } );
- #
- Task IVLocateImageFile( theFileName, theSearchRectangle, theLastLocation := { -32767, -32767 } )
- begin
-
- if ( IVRectangleDefined( theSearchRectangle ) = false )
- begin
- resultList := { 0, 0, "The rectangle passed to IVLocateImageFile was either undefined or contained an undefined element." };
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- resultList := Ivy( "IVLOCATEIMAGE", theFileName, theSearchRectangle, theLastLocation );
-
- resultList := HandleResultList( resultList, "IVLocateImageFile" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-
-
- # IVLocateString( theSearchString, theSearchRect, theFontName, theFontSize, theFontStyle := 0, theLastLocation := { -32767, -32767 } )
- #
- # Purpose:
- # To locate a string of characters on the screen.
- #
- # Inputs:
- # theSearchString - a string containing the characters for which to look.
- #
- # theSearchRect - the screen rectangle in which to look.
- #
- # theFontName - the font name in which the string will appear.
- #
- # theFontSize - the size of the font.
- #
- # theFontStyle - the font style; that is, normal, bold, underline, italic, shadow,
- # outline, extend, condense.
- #
- # theLastLocation - the rectangle (or just its left and top points) where Ivy last found the string. Use
- # this parameter to find the next occurance of a string inside a given search rectangle.
- #
- # Outputs:
- # result - a rectangle describing the location of the image; { left, top,
- # right, bottom }.
- #
- # Notes:
- # If the task does not find the image, it returns the following rectangle { 0, 0, 0, 0 }.
- # To create a font style add the following global constants together in any combination.
- #
- # global kNormal;
- # global kBold;
- # global kItalic;
- # global kUnderline;
- # global kOutline;
- # global kShadow;
- # global kCondense;
- # global kExtend;
- #
- # See also:
- # IVLocateString()
- #
- # Example:
- #
- # global kBold;
- # global kItalic;
- #
- # resultList := IVLocateString( "Hide me", { 0, 0, 640, 480 }, "Chicago", 12, kBold + kItalic );
- #
- Task IVLocateString( theSearchString, theSearchRect, theFontName, theFontSize, theFontStyle := 0, theLastLocation := { -32767, -32767 } )
- begin
-
- if ( IVRectangleDefined( theSearchRect ) = false )
- begin
- resultList := { 0, 0, "The rectangle passed to IVLocateString was either undefined or contained an undefined element." };
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- resultList := Ivy( "IVLOCATESTRING", theSearchString, theSearchRect, theFontName, theFontSize, theFontStyle, theLastLocation );
-
- resultList := HandleResultList( resultList, "IVLocateString" );
- global gIVError := resultList;
-
- if ( resultList[1] <> 0 )
- begin
- return Call( IVGetExceptionHandler(), resultList );
- end;
-
- if ( global gIVResultList )
- return resultList;
- else
- return resultList[2];
- end;
-